LSD Docs/LSD Docs.iso/FILEZ/lsd15.dms/lsd15.adf/PowerWindows2.5.doc.pp/PowerWindows2.5.doc

Text File | 1991-02-19 | 54KB | 1,038 lines

                                POWER WINDOWS 2.5

Typed by RIVER BOY.


PowerWindows 2.5 is the interactive, interface programming aid for the Amiga
computer. It provides you, the programmer, the ability to quickly create and
edit screens, windows, menus, and gadgets for your programs, with none of
the fuss or tedium of coding the necessary structures yourself. All you have
to do is move a mouse and push a button to:

     create new screens and windows;
     edit old screens and windows;
     "grab" (import) windows running elsewhere in the system;
     add, move, delete, or edit window text;
     modify window characteristics;
     include or exclude IDCMP or other window flags;
     add, move, edit or delete a menu;
     add, move, edit or delete items and subitems in a menu;
     add gadgets, move gadgets, clone gadgets, re-size gadgets,
          set gadget characteristics, enter gadget text, and
          delete gadgets;
     add and manipulate Knob, PopUpMenu, and DragGadget
          constructs as used with InovaTools1;
     include IFF brush imagery in your gadgets or menus;
     generate source code for all of the above;
     and save your creations on disk for future editing.

PowerWindows  provides  you  with  instant  feedback,  allowing  you to see
exactly  how  your  creation  will  look without the trial-and-error of the
edit/compile/examine  loop.   You  can effectively see your windows outside
your program, complete with menus, menuitems, subitems, text and gadgets --
almost  as  if  you  were  already  running  your  program.   When  you are
satisfied, select your language and PowerWindows creates the structures for
you.   Save  your design in the intermediate file format so that it will be
available should you ever need to modify or add to it, or generate the same
data for a different language.

NOTE:   You  will  need  to provide the necessary entry points or procedure
names to properly interface the generated code with your program.

REQUIREMENTS:   Amiga  with  512K  RAM  and  at  least one disk drive, with
KickStart/Intuition  version  1.2.  Also required are the necessary include
files for the language of your choice which define the Intuition structures
that PowerWindows generates.


GETTING STARTED:

PowerWindows  requires  no installation.  We recommend that you make a copy
of  PowerWindows  and  put  the original in a safe place, away from hazards
like  fire,  strong  magnetic  fields,  and  pirates.   Use  the  copy as a
"master", and use the original only for making new legal copies.

Unlike  the  program,  you  might require some installation yourself.  This
software expects you to be familiar with the Amiga and with the programming
language  of  your choice.  This means that we won't be defining terms like
drag  bar (no jokes, please) or gadget.  PowerWindows is a serious tool for
serious programmers.

PowerWindows can be run from either the Workbench or the CLI environments.

PowerWindows  starts  with  a  blank,  640  x  200 window, on the Workbench
screen.   This  is  the  "command window".  To see just how simple it is to
create  a PowerWindows interface design, get PowerWindows running and press
the Right-Amiga N key.  This will open a new window on the Workbench screen
called  "Your  new  window".   At this stage you could immediately generate
source  for  "C" or assembler which would create the data needed to exactly
duplicate that window.  But first, let's dress it up a bit..

Start  by resizing the window and positioning it any way you like.  It is a
real Intuition window so the drag bar, depth-arrangement and sizing gadgets
all work.

Next,  press  Right-Amiga A and read the message in the requester that pops
up  at  the  top of the screen.  This message explains how to use the Add a
gadget  command  that we have just invoked.  When you have finished reading
the  text,  press  the  OK  gadget on the requester and position your mouse
somewhere  over  the center of "Your new window" and click the left button.
This  tells  PW2.5 where you want the TopLeft pixel of your gadget's border
to  be  drawn.   Now drag the mouse inside the window and PW2.5 will follow
your movements and size the area of the gadget accordingly.  After you have
dragged the mouse around for a bit, press the HELP key on your keyboard and
PW2.5  will  redisplay  the original message describing what you are doing.
If  you forget which action you are expected to take or just want to CANCEL
an  action once it has already begun, you can always press the HELP key for
a  reminder  and  a chance to change your mind.  For now, just press the OK
gadget  and  put  your  mouse  back into "Your new window".  PowerWindows ,
waiting  for you to make a final decision about the size of the new gadget.
Click inside the window to tell PW when you are done.

Now  you  have a real window with a real BOOLEAN gadget in it, but we still
need  a  menu.  So press Right-Amiga M and PW will open a requester used to
specify several options about menus, but right now we just want to key in a
name  for  our  first  menu,  so  just  type  in  "My  First Menu" into the
preactivated string gadget labeled MENU TEXT.  Next press the OK gadget and
the  requester  will close.  Your window now has a real menu attached to it
with one menuitem called "dummy".  If you need proof, click on the drag bar
of  "Your  new  window",  followed by the right mouse button.  Your menu is
there  and  it  looks  exactly the way it would look in your program if you
generated  source  code  for this window right now.  So let's do that right
now.

Press  Right-Amiga  G and a requester will open with the names of the three
language  generators  that PW2.5 has built-in listed in gadgets at the top.
Press  on  the  language you want and then press on the word OUTPUT (not in
the  string  gadget  to  the  right  of  the word) and the InovaTools1 file
requester  will  open allowing you to specify the complete filename for the
output  file you want to generate.  Choose a filename like "ram:test.c", or
at least some filename that you wont mind letting PW use.

Once  you  have  specified  a  filename for our little test window's source
code,  the file requester will close and stuff the filename into the OUTPUT
string  gadget.  If you already know the filename, of course you can key it
directly  in  this  box.   Finally,  press the OK gadget on the source code
generation requester and PW2.5 will write a file with all the data you need
to duplicate this simple interface in your own software.

Now,  we  want  to  save this design for later editing, of course, so press
Right-Amiga  S  and  the file requester will reappear to let you indicate a
save  filename.  By default PW will save your file with the ".pw" extension
added  to  the  name, but you can use any extension you want by typing into
the  box  on the file requester labeled Type and pressing RETURN, or use no
extension  at  all  by  deleting  all characters in this field and pressing
RETURN.   Once you have specified the filename press the Save gadget on the
file  requester  and  the  save will be made.  In the case of a disk error,
PowerWindows will report it to you and allow you to try the save again.

Now  that  the file is saved, you can Quit PW2.5 and come back to that same
file  anytime  using  the Right-Amiga L option, and then just pick right up
where you left it last time.

That  was  a  simple  PowerWindows  2.5  editing session.  Now use the menu
button to see the main menustrip, which consists of seven primary menus:

     Project
     Screens
     Windows
     Menus
     Gadgets
     Knobs
     Preferences

Each  of  the  menus  listed above are discussed in the sections following.
This manual is organized in the same way that the menus are organized.


PROJECT:

Under the Project menu you will find the following:

     Generate source code
     Save configuration
     Save screen and/or windows
     Load screen and/or windows

     Kill everything

     Quit...

Generate source code is the whole point of PowerWindows.  This command lets
you  specify  the  language of your choice and several other options.  (For
languages  other  than  "C"  and 68000 assembler, you must use the specific
language translator program provided for that language, which you will find
on  your distribution disk.  These translator programs use the intermediate
file  format  generated  by the Save screen and/or windows command.) Before
starting the code generation, you must specify the OUTPUT filename.  If you
don't know the filename to use, you can click on the word OUTPUT for a file
requester.   You  may also specify a HEADER filename.  The HEADER file is a
file  that  you  wish  copied into the start of the source generated by PW.
This  file  may  contain definitions, include statements, or anything else.
You may click on the word HEADER for a file requester if you need one.

You  can also control which "sections" of the source code to generate.  For
example,  assume you have created a source file with PowerWindows, and then
edited  it  for some particular purpose; if you need to edit that design in
the  future  and  regenerate the source code, PW will allow you to generate
source for only those parts of the design that have changed.  Just turn off
the  sections  that  you  do  not  want  generated.   The sections include:
SCREEN,  PALETTE,  WINDOWS, GADGETS, MENUS, WINDOWTEXT, RENDER (BORDER ONLY
and IMAGE ONLY gadgets), and EVENTS (the event handler).

The  LOCAL  STRUCTURES option instructs PW to make all structures generated
local,  if  the  target  language  supports  such a concept.  An example is
static structures in C.  Finally, the BORDERS/IMAGES GADGET option tells PW
to generate a special gadget as a link for the render of any BORDER ONLY or
IMAGE  ONLY  gadgets (see Define gadget type for details) that may exist in
your design.  In other words, rather than create the standalone linked list
of  Borders/Images that would normally be created, PW will link those lists
into  a  gadget  designed just for rendering that data.  The gadgets have a
size  of  zero,  use  no highlighting and are placed in the extreme TopLeft
corner of the window that they inhabit.

Save  configuration  lets  you  save your current Preferences settings to a
file  called  "devs:pw2-configuration".   This file is automatically loaded
when  PW is invoked.  Note that your preferences are also saved to every PW
intermediate file that you make, and are loaded from those files.

Save  screen  and/or  windows  will  save  information to a file about your
screen  and  windows in a format that PowerWindows can read to recreate it.
If you wish to retain the ability to edit your current design, you must use
this  option.  We suggest that you append ".PW" to the filename to indicate
what  kind of file your are saving.  (The file requester also automatically
looks  for  .PW  files  as  a  default.) At any time in the future, you can
select  Load screen and/or windows from the Project menu and read this file
to  examine  and edit this design.  Your PW Preferences settings and source
code generation options are also stored in this file.  Note that additional
PW  support programs, such as generators for other languages, use this type
of  file.   In  the  future, INOVATRONICS will provide tools allowing other
uses for this format.

Load  screen  and/or windows loads a file generated in the above manner and
opens  the  windows  and screen contained therein.  Note that PW will merge
the  incoming  windows with any current windows you are working with.  If a
custom  screen  is found in the file, and you already have a custom screen,
PW  will  prompt  you to ask if you wish to replace the current screen with
the  one  from  the file.  The Preferences in use are always those from the
most recently loaded intermediate file.

Once  you  have  loaded  a  file in this way, you can manipulate all of the
objects  in  your  design,  exactly  as if you had just created them.  This
allows  you to easily play with interface designs, move this object here or
there, and experiment.

One  extremely  practical  way  to  make use of this feature is to create a
"toolbox"  window of gadgets or knobs that you use on a regular basis, then
save that window as a normal PW intermediate file.  Then, whenever you need
a  gadget  just  like  one of the ones in your toolbox, you can re-load the
window  and move or clone a gadget out of that window, and into the one you
are  currently  designing.  After you have what you need from your toolbox,
you can simply remove it with the Kill window command.

Kill everything will close any custom screen and all windows with which you
are currently working.  There is no undo feature.  Be warned.

Quit...   means  just  that.   Make  sure  you've saved an editable file if
there's  any  chance  you might need to change the display on which you are
working.   (Re-creating a complex window with many menus and gadgets is far
easier   with  PowerWindows  than  without  it,  but  it  IS  still  work.)
PowerWindows will ask you if you wish to abandon any changes you have made,
if you have not saved at least an editable file to disk.


SCREENS:

You can design custom screens and palettes with the Screens functions.

Define  screen  type  will  present  you  with  a window with which you can
determine  your  screen's  dimensions, the number of bitplanes it uses, the
pen  numbers,  default font and title for the screen.  Use these gadgets to
control  the  type  of  screen you get, select the CUSTOMSCREEN gadget, and
press  OK.   A  new  screen will appear with the indicated characteristics.
All  windows  that  you  later  open will appear on this screen, or, if you
already have windows open, they will be moved to this screen.  Four gadgets
are  provided for selecting any one of the four standard NTSC screen sizes,
however  you  may  key  any  dimensions  you like into the Width and Height
gadgets  at  the top of the requester.  PW will not verify that the numbers
you  have  chosen  are  legal; this is your responsibility.  To return to a
Workbench screen, select the WBENCHSCREEN gadget and press OK.

Several flags appear under the Screen Flags section of this requester which
are  not  WYSIWYG,  but  will  be  generated in your source code.  The same
applies to the CUSTOMBITMAP POINTER string and the GADGETLIST string.

To  move  quickly  between the PW command window, which is on the Workbench
screen, and your custom screen, you can use the F1 and F2 keys.

Screen  Palette  brings up a palette editor which you can use to change the
RGB  settings  for  your  screen's colors.  The colors on the requester are
oriented  left-to-right  beginning  with  color  0.   You  can use the READ
PALETTE FROM IFF gadget to specify an IFF brush filename from which to read
a  palette.   If  you  need  a file requester to help you select the proper
file,  click  over  the  phrase  READ PALETTE FROM IFF.  If you modify your
palette,  only  to later change your screen definition, the palette changes
may  be  lost.   A  color  palette  is maintained through screen definition
changes  only if the number of bitplanes used in the old and the new custom
screens is the same.


WINDOWS:

PowerWindows  2.5  lets you work with any number of windows simultaneously.
However,  all the commands relating to windowtext and menus operate only on
the context window.  For example, if you have two windows open and you tell
PW  to Redisplay, it will redisplay the current context window.  You switch
context  windows  by  clicking  inside  the  window that you want to become
active.   You  can switch context windows only when PW is waiting for input
at the main menu level.

Under the Windows menu heading you'll see:

     Open new window
     Grab a window
     Redisplay
     Clean up
     Edit window characteristics
     Kill window
     Write window text
     Move window text
     Edit window text

     Delete window text

Open  new window opens a new Intuition window on the Workbench screen or on
your  custom  screen  if  you  have  made one.  You can do anything to this
window  that you like because it is an actual window.  At various times, PW
will  read  information from this window's structure regarding its position
and  size,  but  you can play with it freely.  The new window automatically
becomes  the  context window for windowtext and menus.  To quickly reselect
the  PW  command  window,  you  can  press  F1, click inside the PW command
window,  or  if  Auto  select is on, just click inside any one of your edit
windows.

Grab  a  window  is one of the most powerful PW commands.  It allows you to
import  any window running at the time as a PowerWindows construct and edit
it  as  if you had generated it manually.  After selecting this option, you
will have a new menustrip with the following menus:

     Screens
     Other

On  the  Screens  menu  you  will  find  a list of all screens open at that
moment,  and  a  list  of  all windows open on each screen will be shown as
subitems  to  that screen.  The windows and screens are identified by their
titles.   If  a  screen  or  window has no title, its item will appear as a
blank.   To  grab  one  of  the  windows listed, just select its name.  The
window,  with  all  of  its  menus and gadgets will be imported into PW for
instant  editing.   Note that some things are not grabbed, such as imagery,
borders,  or  text that were drawn into the window individually and are not
connected  to  any  gadget  or  menu.   For each gadget grabbed that uses a
border  for  render, a custom border is created.  You may delete or replace
this border by doing border work on that gadget.  All menus are set to USER
FORMATTING  when grabbed because PW wants to maintain the original look and
positioning  of  the  grabbed  menus.   If you are grabbing a window from a
screen   of  a  resolution  different  from  the  one  you  are  designing,
PowerWindows may have to change the size or origin of the window to make it
fit.  The Other menu allows you to return to the main menu.

Redisplay  refreshes  your current window, cleaning up any display problems
that might result from your editing.  The raster of your window is blanked,
then all gadgets, knobs and windowtext are redrawn into it.

Clean  up  is  provided to ensure that all gadgets and knobs in your window
are  actually  in the displayable area of your window.  For example, if you
have put a knob or gadget in the far right-hand side of your window and you
then  make the window more narrow by resizing it to the left, those gadgets
and/or  knobs  may  be  no  longer  in your view.  This can cause problems,
because in order to manipulate a gadget or knob with PowerWindows, you must
be  able  to  select it with the mouse.  The Clean up command will move any
gadgets  or  knobs  which are outside the display area back into it.  Also,
because  of  gadget  WYSIWYG relativity, it is possible for you to create a
gadget  with  a  hitbox which has a negative size.  PW will detect any such
problems and correct them when this command is used.

Edit  window  characteristics  gives  you  the  opportunity  to specify the
following:

     Detail and block rendering pens;
     Minimum and maximum window dimensions:
     Current window dimensions;
     Current window position;
     Window title;
     Window type (window or requester)
     Window ID prefix (added to all structure names for this window
     IDCMP flags and window flags

The  IDCMP flags in this window can be toggled ON or OFF to include them or
not  in  the generated source code, but during editing the window has IDCMP
flags used by PowerWindows internally.  (To see what they are, try grabbing
one!)  Of  the  normal  window  flags,  these  are  WYSIWYG:   WINDOWCLOSE,
WINDOWDRAG, WINDOWDEPTH, WINDOWSIZE, SIZEBBOTTOM, SIZEBRIGHT, BACKDROP, and
BORDERLESS.   See the Amiga ROM Kernal manuals for complete descriptions of
the flags listed on this display.

If  you  want  PW  to  make  a  Requester structure rather than a NewWindow
structure  at  source  code generation time, you can hit the gadget labeled
TYPE, and it will toggle between WINDOW and REQUESTER.

Kill  window  will remove the current window.  Be sure to select the window
you want to destroy before using this option, as there is no UNDO command.

Write  window  text lets you write a string of text to be displayed in your
window.   After  keying  in the text, click OK and move your pointer to the
location  in  your  window  where you want the upper left-hand pixel of the
first  character  of the text to appear.  Click here (the text appears) and
drag  the pointer to position the text more exactly.  Click again when your
text  is  properly  positioned.   (Windowtext and gadgettext are different.
Windowtext is relative to a window and in the source code is generated as a
linked  list  of  IntuiText  structures  that  you can draw into the window
yourself  with  a  single  PrintIText  call.   Gadgettext  is relative to a
gadget.  If you move the gadget, the text will move with it.  If you delete
a gadget -- BAM!  -- the text is gone too.  Gadgettext is also generated in
source as a linked list of IntuiText structures, but they are referenced by
the  gadget they were designed with and will be automatically rendered when
their parent gadgets are rendered.)

Edit  window  text  displays  as subitems one or more text strings that you
have  previously entered for this window.  (If none have been entered, this
and subsequent menuitems are disabled.) Just select the text string subitem
that  you  would  like to edit.  This gives you a window from which you can
choose  text pens, drawmode and font (default, TOPAZ-SIXTY or TOPAZ-EIGHTY)
as  well  as  edit  the text and its offsets from the TOPLeft corner of the
window.  All source code needed to duplicate your text will be generated by
PowerWindows,  including TextAttr structures for the fonts.  After editing,
the window will be redisplayed with any text changes shown.

Move window text gives you the ability to move individual strings of window
text around in the window.  The movement of the text within the window will
be  relative  to  the  position of your pointer when you first click inside
your window.  This gives you the ability to click somewhere near your text,
but not on it, so that you can see the entire text string as you move it.

Delete  window  text  enables you to remove unwanted text from your window.
Just select the text to kill and POOF!  It's gone.


MENUS:

Making menus with PowerWindows 2.5 is very easy.  The menus that you create
are,  at  all  times, real menus, attached to the window with which you are
working.   Therefore,  you  can  see what your menu looks like at any time.
Plus,  if you are working with a custom screen, you can see the menu in the
resolution  in  which  it  will be used.  To see the menus for a particular
window,  you must select that window.  If the Auto select preference is ON,
you  can  only  select the window by clicking on one of its system gadgets,
like a drag bar or foreground gadget.  If the window has no system gadgets,
you  can  add them with the Edit window characteristics command, or you can
turn off Auto select and just click inside the window.

Under  normal conditions, all menu elements are automatically positioned by
Power Windows.  This is called AUTO FORMATTING.  PW will always do its best
to  see  that  the  menuitems  and  subitems are visible when the menus are
rendered,  and  are  attractively  arranged.  However, you can position the
items  yourself,  if  you like, by setting the USER FORMATTING flag for the
menu  or  item  and specifying the needed pixel values.  But be careful; if
you use irrational values, your computer will respond irrationally!  If you
do  not  set the USER FORMATTING flag, PW will ignore any pixel values that
you set.

The  Menus  menu  deals  with  menus, menuitems, and menu subitems for your
current  window.   Your menus are dynamically updated every time you make a
change  to them.  You can append a menu to the end of the menu tree, or you
can  insert  a  new  menu in front of others.  You can rearrange the menus,
delete  them,  etc.  You can also do the same things with the menuitems for
each  menu  and  with  the  subitems  for  each  menuitem.   You can attach
Amiga-keys  to menuitems and subitems, and have the items checked/unchecked
or  enabled/disabled  by Intuition.  You can instruct Intuition to un-check
certain  menuitems or subitems when others are selected.  You can also load
imagery for the rendering of menuitems and subitems.

The Menus menu shows you:

     Append a menu
     Insert a menu before...
     Move a menu
     Edit a menu
     Work on menuitems for...

     Delete a menu

Append a menu lets you to enter the name of a new menu, choose AUTO or USER
FORMATTING, and set/reset the MENUENABLED flag.  After you OK the settings,
PowerWindows  creates a menu with that name and attaches a "dummy" menuitem
to  it.   (This  dummy goes away when you add a real menuitem to the menu.)
All menus created in this manner are appended to your menustrip (i.e., list
of menus).

Insert  a  menu before...  shows you the menus that exist.  When you select
one  of  them,  you will be prompted for the name of the new menu to insert
before the selected one.

Please  note  that  only  the first 15 characters of each menu name will be
displayed  here;  the full menu name will be used in your window and in any
generated  source code.  This truncation applies to menuitem names, subitem
names, gadgettext and windowtext, as well.

Move  a  menu lets you move a menu toward the back of the list (the end) or
toward  the  front  of  the list (the start).  You can move a menu only one
position  at a time, so you may have to invoke Move a menu several times to
get things just so.

Edit a menu lets you change all the settings of a selected menu.

Work  on  menuitems  for...   allows you to attach menuitems, subitems, and
their options to the menu you select.  See the next section for details.

Delete  a  menu removes the selected menu from the menu tree.  Use this one
with  caution,  as  it  removes  everything  having  to  do with that menu,
menuitems, subitems and all.


MENUITEMS:

When  you  select  a  menu  form  Work on menuitems for..., you are given a
completely new menustrip from which to work.  It has two menus:

     MenuItems
     Other

Menuitems looks, and is, similar to the Menus menu, but "menuitem" replaces
"menu"  and  "subitem" replaces "menuitem", and there is one more choice on
the  menu;  Work  on  images  for..."  Basically,  however,  you  can do to
menuitems what you did to menus:

     Append a menuitem
     Insert a menuitem before...
     Move a menuitem
     Edit a menuitem
     Work on images for...
     Work on subitems for...

     Delete a menuitem

Under  AUTO  FORMATTING  the  width of the longest hit box in your menuitem
list  determines  the  width  of all the menuitem hit boxes in the menuitem
list  for  that  menu.  You can pad your menuitem names with spaces to make
the box wider, or play with the choices you get in the editing window.

Append a menuitem, Insert a menuitem before..., and Edit a menuitem all use
a  window  that allows you to specify a number of Intuition menuitem flags,
text  for  the item, as well as an alternate command key for the item.  You
can  also control the presentation of the IntuiText rendered in your window
with  this  option.   The  ROOM  FOR CHECK and ROOM FOR ALTKEY provide some
additional spacing to the left and right of the item render for a checkmark
and  an  alternate command key, respectively.  The FUNCTION gadget lets you
key  in a function or vector name for execution when this item is selected.
This  execution  is performed in conjunction with the event-handler (please
see Using the event handler for details.)

Also  contained  in  this  window is a menu which allows you to specify the
items  which  the  current  item  should mutually-exclude.  (Mutual-exclude
refers  to  one  item  which,  when selected, will un-check a list of other
items  on  the  same  menu, or other subitems of the same menuitem.) Notice
that  the item upon which you are working is also listed here because it is
perfectly  legal to make an item exclude itself, though it rarely makes any
sense.   As  you  move,  insert  or  delete  items  from  the  menu,  these
mutual-exclude values are automatically maintained by PW2.5.

Work  on  images  for...  allows you to load or delete IFF brush imagery to
use  for menuitem rendering.  You can load both the render (unselected) and
select  (selected) imagery.  PW automatically makes the select boxes of the
items in the list wide enough for the images to be attractively integrated,
even if you mix images and text on a single item list.

Work  on  subitems  for...   sets  up  yet  another new menu, just slightly
different from the last one:

     Append a subitem
     Subitem columns(1)
     Insert a subitem before...
     Move a subitem
     Edit a subitem
     Work on images for...

     Delete a subitem

The slight difference is Subitem columns.  With this option you can display
your subitems in up to 9 columns.

Other  on  the Subitem menu offers a return to the Main menu or a return to
the Menuitem menu, while Other on the Menuitem menu only lets you return to
the Main menu.


GADGETS:

All  gadgets  created  by  PowerWindows  are  rectangular,  but they can be
virtually  any size from a few pixels to the entire area of the window, and
with  the  Clone  a  gadget  feature you can make very professional-looking
screens  filled  with  gadgetry  of  varying sorts and colors.  PW lets you
create  all  three Intuition gadget types, BOOLEAN, STRING and PROPORTIONAL
and work with them in a what you see is what you get fashion.  You can also
load  custom  imagery  for  the  the  render  (unselected)  and  the select
(selected)  fields  of  a  gadget.   Additionally,  most of the flags which
control the gadget's appearance are also WYSIWYG.

With  PowerWindows version 2.5, you can also work with two special types of
BOOLEAN  gadgets:   PopUpGadgets and DragGadgets.  Both of these new gadget
types  are  meant  to  be  used with the InovaTools1 package available from
INOVATRONICS,  Inc.   If  you  do  not  intend to use InovaTools1 with your
software,  then  do  not use these new gadgets types in your design.  PW2.5
has  the  support routines for the InovaTools1 functions built-in to it, so
you can design these special items, even if you cannot use them in your own
programs.

PopUpGadgets are BOOLEAN gadgets that, when pressed, will display a menu of
your  design  under  the  mouse  and allow the user to select a menuitem or
subitem  just  as  if a normal intuition menu were being used.  You specify
that  you  want a gadget to be a PopUpGadget through the Define gadget type
command.   Then  you  may  edit the menu attached to the gadget through the
Work  on  PopUpGadget  menuitems command.  After making a PopUpGadget, when
you  click  on  the  gadget  your  special menu will be displayed under the
mouse.

DragGadgets  are  BOOLEAN  gadgets which use an image for render and may be
dragged around the screen.  You can make the gadget stay where it is put or
rubber-band  back, move around just in the window in which they are defined
or allow them to move anywhere on the screen!  You can also control the way
in  which  the render image is displayed while the gadget is being dragged,
and the dimensions of the area in which the gadget can move.  Once you have
created  a  DragGadget,  you  can  click on it and drag it anywhere in your
window.

Both  of  these gadget types are fully WYSIWYG within PowerWindows.  A full
discussion of their properties and how to control them are beyond the scope
of  this  documentation.   You  must  refer  to  the InovaTools1 manual for
further information.

Under the Gadgets menu you'll find:

     Add a gadget
     Move a gadget
     Clone a gadget
     Re-size a gadget
     Define gadget type
     Work on gadget borders
     Work on gadget text
     Work on gadget images
     Work on PopUpGadget menuitems

     Move gadget to start of list
     Choose gadget successor
     Move gadget to end of list

     Delete a gadget

Add  a gadget waits for you to click in one of your windows to position the
TopLeft  corner of your gadget's border.  Drag the mouse to size the gadget
appropriately.   Click  the  mouse  button again and the box becomes a real
BOOLEAN  gadget,  hooked  into your window.  Note that your ability to size
the  gadget, and then later to move it, may be impeded by the status of the
Gadget  collision  checking flag which, when on, will prevent the bisection
of  one  gadget  by  another.   You  may  wish to disable this function for
special applications, but be aware that the designers of Intuition strongly
discourage the practice of overlapping or intersecting gadgets.

Move  a  gadget lets you change the position of a gadget by clicking inside
the  gadget  and dragging it to a new location.  Any associated gadget text
will  be moved also.  That is, its position relative to the gadget will not
change.   When  moving  STRING  gadgets,  after selecting the gadget, press
return.   After  that,  the  gadget  may be moved normally.  Press the left
mouse  button  when  it  is  properly  positioned.   Similarly, always move
PROPORTIONAL  gadgets  by  their knobs, not by clicking inside the gadget's
container.

You may move a gadget from one of your windows to another by simply picking
the  gadget  to  move  and moving your mouse until it is over the window to
which  you  wish  to  move  the gadget.  Then click the mouse again and the
gadget will be removed from the old window and deposited in the new window.

Clone a gadget lets you duplicate a gadget exactly, both in terms of hitbox
size  and  in  terms of gadget flags, text, and imagery or borders.  Select
the  gadget  to clone and a new gadget, slightly offset to the BottomRight,
will be created.  Now drag the pointer to position the duplicate gadget and
click the left mouse button when you are finished.

You can clone gadgets from one window to another in exactly the same manner
as they are moved from one window to another, as described above.

Re-size  a  gadget  gives  you  another opportunity to get that gadget just
right.  Click and hold the select button when the pointer is on the desired
gadget.   Dragging  the  mouse  around  will re-size the gadget.  Click the
button again when the gadget is the correct size.

Define  gadget  type,  after selecting a gadget to work on, gives you a new
window  full of various flag settings and decisions you can make concerning
your  gadget.  From this screen, you can determine the gadget type, set its
size  and  origin locations, and specify various data for the generation of
your gadget's source code.

A few Define gadget type notes:

The  relativity  flags GRELRIGHT, GRELBOTTOM, GRELWIDTH, and GRELHEIGHT, if
selected,  ARE  put  into  effect  while  in  PowerWindows.  Therefore, any
changes  made  to  the  size  of  the  window in which the relative gadgets
reside,  will  effect the position and/or size of the relative gadgets.  Be
careful:  it is possible, for instance, to make a gadget with the GRELWIDTH
flag  set, then resize its containing window to be so small that the gadget
attains  negative  dimensions.   Intuition  will not object, but it will be
impossible  for your user or yourself to select this gadget.  Use the Clean
up  command  from the Windows menu to fix any problems arising from the use
of this WYSIWYG feature.

BORDER-ONLY  and  IMAGE-ONLY  gadgets  are gadgets only in the context of a
PowerWindows  editing  session.  At the time of source code generation, all
of  the borders of the BORDER-ONLY gadgets will be written as a linked list
of Border structures, one for each BORDER-ONLY gadget, and likewise for the
IMAGE-ONLY  gadgets.   Any  text  associated  with  these  gadgets  is  NOT
GENERATED  AT  ALL.  Use BORDER-ONLY gadgets to draw boxes around groups of
gadgets  and  text,  as  we  have done with this screen, and use IMAGE-ONLY
gadgets to place various images around your display.

PopUpGadgets are BOOLEAN gadgets that have a PopUpMenu attached to them for
use with InovaTools1.

DragGadgets  are BOOLEAN gadgets that can be dragged around the display and
use  imagery  for  render.  Selecting this option will bring up a requester
allowing  you  to indicate the dimensions of the DragGadget's bounding-box,
as  well  as  the various flags used by DragGadgets.  Also, if the language
you are working with supports vectored execution, you can specify a routine
to  be  executed each time the DragGadget is moved by the user.  The string
describing this routine is generated in your source code.

In  the BOOLMASK gadget, you can specify a pointer to a BOOLMASK for use in
a BoolInfo structure.  PW will not generate a BoolInfo structure unless you
put a string into this field.

In  the  EXCLUDE,  GADGETID  and  USERDATA  gadgets, you can enter any text
strings  that  you want used for these same fields in the Gadget structure.
Because  these  fields are not used by Intuition, you can use them for your
own  data.  You must provide any data necessary to resolve these references
at compile or run time.

The  FUNCTION  gadget  lets you specify a function or vector which is to be
executed  when  this  gadget  is selected.  See Using the event-handler for
more details.

In  the SOURCE LABEL gadget, you can enter the exact text for the structure
name  to  use  when  generating  source for this gadget.  Does not apply to
BORDER-ONLY or IMAGE-ONLY gadgets.

The  number  in  the string gadget LENGTH field must include one extra byte
for the end-of-line null byte required by Intuition.

If  you turn on the UNDOBUFFER gadget, PW will generate one undo buffer for
all  those  gadgets  that  refer to it.  The buffer will be as large as the
largest string gadget buffer.

The HBODY and VBODY values are a convenient way to indicate the size of the
AUTOKNOB  of  proportional gadgets and the distance which the knob can move
each  time the gadget's container is hit.  A value of 10, for example, will
make  the  AUTOKNOB  1/10 the size of the entire container and it will move
1/10 of the container each time the container is hit.

Please  see  the  Amiga ROM Kernal manuals for complete descriptions of all
the Gadget flags listed on this screen.

Work  on  gadget borders concerns your control of a gadget's border.  After
you  choose the gadget to work with, you have a new menu with the following
topics:

     Borders
     Other

On  the  Borders  menu,  you  will  find three functions for the drawing of
custom  borders  (1.   freehand  - where you click in your window, drag and
click  to  set the end-point of that vector, and double-click when down; 2.
rectangle  -  where you click for the TopLeft corner of the rectangle, drag
and  click when done; and 3.  square - in which you click to set the center
of  the square and drag to define its size), a command to edit the offsets,
drawmode  and  pen  number  of  the  border  (for custom border or standard
border),  and  a  command to delete any custom border.  The Other menu lets
you  turn  off the standard border, pick a new gadget to work on, or return
to the main menu.

If  you  turn  off  the  standard border (not the same as border-only), the
gadget  border  will  still  be  displayed  by PowerWindows for purposes of
editing  and  identification.  Any source code generated, however, will not
have  a  gadget  border  structure  referenced  or  generated.  In order to
generate a gadget with absolutely no render, you MUST turn off the standard
border.

Work  on  gadget text gives you a new menu that is identical in function to
the  functions  concerning  windowtext in the Windows menu.  Note, however,
that  windowtext  is  relative  to  a  window  and  gadgettext to a gadget.
Otherwise  the principles are the same.  Write the text, position it in the
window  by  clicking and dragging the mouse, and click again when all is as
it should be.

Work  on  gadget  images  lets you pick a gadget for which to load imagery,
then  gives  you  a new menustrip relating to imagery for that gadget.  You
can  load  an  IFF  brush for the gadget render of the gadget select image,
edit  the offsets for the image, make the gadget hitbox the exact same size
as the image, or delete image.  PW will automatically set the correct flags
in  the  gadget  structure  allowing you to use the image, delete it, etc.,
without worrying about the render or highlighting flags.

Work  on  PopUpGadget  menuitems  allows you to edit the menu attached to a
PopUpGadget  just as if it were a normal PowerWindows menu.  After choosing
this  option,  simply click on the PopUpGadget with which you wish to work,
and  PW2.5 will give you a new menustrip for editing the menuitems attached
to your PopUpGadget.  You can do anything to a PopUpGadget's menuitems that
you  can  do  to  a  normal  menu's  items,  including  the use of imagery,
subitems,  various highlighting methods and mutual-exclusion of other items
on  the  same  PopUpMenu.   You  cannot, however, use alternate command key
sequences  for PopUpGadgets because Intuition would confuse these keys with
those reserved for common Amiga menus.

Move gadget to start of list lets you pick a gadget to move to the start of
the  gadget  list.  This command and Move gadget to end of list can be used
to  crate  lists of gadgets in an exact order.  This lets you use only part
of a gadget list in a given situation.

Specify  gadget  successor lets you indicate that "this" gadget comes right
after  "that"  gadget  in the list.  In the event that two gadgets overlap,
this command lets you control which gadget is in "front".

Delete  a  gadget  deletes  whatever gadget you choose.  To delete a string
gadget,  you  must select and press RETURN.  Be careful!  There is no going
back.


KNOBS:

Knobs  are  special, new input devices supported by InovaTools1.  They have
the appearance of circular, analog-type dials.  They can be rendered in any
of  the  standard  resolutions and are highly configurable.  To use a knob,
simply  click in the body of the knob.  If the arrow of the knob (the dial,
in  other  words)  is  not  already  at  the position on the knob where you
clicked,  it  will  move there.  Then, as you move the mouse the knob arrow
will  move around the knob to a new setting.  To stop moving the dial, just
release the mouse select button.

A  complete  discussion  of knob properties can be found in the InovaTools1
documentation,  and  you  must  have  that  software in order to make knobs
function in your software.

If  you  look  at  the  Knobs  menu,  you  will  see  the following options
available:

     Add a knob
     Move a knob
     Clone a knob
     Re-size a knob
     Edit knob parameters

     Delete a knob

Add  a knob works very much like Add a gadget.  After choosing this option,
click  at  the point inside your window at which you want the center of the
knob  to  appear.   Then you simply drag your mouse to size the knob.  When
the outline of the knob's diameter looks correct to you, click on the mouse
again  inside the window and a real Knob will be added to your window.  You
can  change  its  size,  position  and  many  other  options with the other
commands from this menu.

Move a knob works in this way:  click on the knob you want to move, drag it
(even  to  a  new  window  if you like) and click again when it is properly
placed.   If  you  move  a knob to another window, the knob will be removed
from the window of origin, and appended to the KnobList of the destination.

Clone  a  knob is the functional counterpart of Clone a gadget.  Just click
on  the  knob to clone and an exact duplicate knob will be created that you
can  then move to someplace in that same window or to another window if you
so choose.

Re-size  a  knob  allows you to click on the knob to resize, drag the mouse
and  then  click  again  when  the knob has reached the desired dimensions.
Because  certain  rasters  and  memory must be allocated in order to fill a
knob  with a particular color, making a knob too large can result in a knob
that cannot be filled.

Edit  knob parameters will wait for you to select the knob you want to edit
with  the  mouse, then will open a requester with gadgets inside it for all
of  the  various  flags  and  settings  that  can  be determined for knobs.
Although you must refer to the InovaTools1 manual for a thorough discussion
of all these parameters, below is a short list of the items you can control
with this command:

     X and Y coordinates of the knob's center;
     knob flags, including DRAW, FILL, COMPLEMENT, RANGED,
          CALCVALUE, MARKED, and MARKENDS;
     the current settings for the knob's position, range of
          movement, and the number of unique steps in its range;
     the radius of the knob and the length of the knob's arrow
          (dial);
     the colors used for rendering the knob;
     the label to be used in the generated source code for this
          knob;
     fields to name the text strings for the UpdateRoutine,
          KnobID, and UserData fields of the Knob structure.

When  you  have  properly  set all of the knob's parameters click on the OK
gadget  and  the  knob  you  changed  will  be redisplayed, reflecting your
changes.   Note  that  if you happen to accidentally move a knob beyond the
edge  of  your  window, you may use the Clean up command to bring all knobs
and gadgets back into the boundaries of a selected window.

Delete  a  knob  waits  for you to click on the knob you want to delete and
then  removes  it  from  the  KnobList  of  its window.  The window is then
redrawn without the knob.


PREFERENCES:

This  menu  gives  you  some flexibility in using PowerWindows 2.5.  In it,
you'll see:

     OK prompts
     PW backdrop
     Auto Redraw
     Auto Select
     Mouse coordinates
     Gadget collision checking
     Image color remapping
     Image compression
     Trim extra bitplanes
     Source code comments
     Source code spacing (TAB)

The  default  condition  for all of these settings is ON, except for the PW
backdrop  option.  However, these settings, along with other relevant data,
are  stored  in  each  PW intermediate file that you save, and are restored
when the PW intermediate file is reloaded.

OK  prompts,  when checked, gives you a prompting requester at the start of
many  gadget  and  text related functions.  At these prompts, you also have
the  ability  of  cancelling your action.  You can disable these prompts by
un-checking  OK  prompts  in this menu.  You can get the prompt back at any
time  in the middle of a function by pressing the "HELP" key.  You will get
the original help prompt back with the same chance to cancel the operation.

PW  backdrop  controls  the PW command window.  If this is checked, then it
becomes  a  backdrop  window.   This means that no window opened can appear
behind  the  PW command window.  Normally, this provides a working area for
your  custom  window  design.   However, if you wish to make the PW command
window smaller, or design your own backdrop window, then use this option to
make PW use a standard window.

Auto  redraw  lets  you  stop PowerWindows from redrawing your window after
every change you make.

Auto  select, when checked, tells PowerWindows that each time you click the
left  mouse button, or select a gadget, in one of your windows, that the PW
command  window  should  be  activated.   This way, the PW menus are always
available.  However, if you are doing a significant amount of menu editing,
and  are not using a drag bar in your window for safe selects, then you may
wish to turn this function off so that you can easily select your window in
order to inspect your menus.

Mouse  coordinates, when set, shows the absolute X and Y coordinates of the
mouse  on  the  right  side  of  the  PW command window's title bar, during
certain gadget and text related functions.

Gadget  collision  checking,  when checked, makes sure that your gadget hit
boxes  do  not bisect one another.  If you disable this, gadgets can appear
on  top  of  each  other, which can cause some problems for the user.  Note
that the creators of Intuition strongly discourage this practice.

Image  color  remapping instructs PW to modify the colors of each IFF brush
image  that  you  load.  The purpose of the modification is to best realize
the  original intent of the colors used in the IFF image, when working with
a palette which is different from that of the image.

Image  compression makes PowerWindows detect and remove any bitplanes in an
image  which  are  all  0  or  all  1.   The image variables, PlanePick and
PlaneOnOff  are  adjusted  accordingly.   This saves memory and reduces the
amount of ImageData PW generates.  Note, however, that if PW performs Image
color  remapping  on  an  image,  then  planes  that  were  candidates  for
compression may be used to represent the remapped colors.

Trim  extra  bitplanes  forces  each  image  loaded  to  consist of no more
bitplanes  than in the screen onto which it is loaded.  If the image is not
to  be moved at runtime, from one resolution to another, this option simply
throws away undisplayed data.

Source code comments, when checked, lets you tell PowerWindows to include a
comment  for  almost  every  line of generated source code, explaining what
element  of  each  structure  that  source  line represents.  Excluding the
comments results in a smaller, less understandable source file.

Source  code  spacing  allows  you to set the number of spaces PowerWindows
will  indent each source line with.  Alternatively, you can choose TAB as a
separator, which is the default.


OTHER TOPICS:

Repeating commands:  The F10 key will repeat the last menu command that you
gave  to PW.  In several instances, however, PW will not allow a command to
be  repeated  because  it  is  no longer valid or because your verification
should be required, as in the deletion of text or menus, etc.

Cancelling commands:  When using the gadget and text commands which require
you  to  click  in your window, you can press the "HELP" key at any time to
redisplay  the  OK  prompt  that explains the current procedure.  From that
prompt, you can press CANCEL to abort the current command.

Using  the event-handler:  The event-handler that PowerWindows can generate
uses  the  data  that  you  would  normally receive in an IntuiMessage from
Intuition.   You  can specify function addresses for gadgets, nemuitems and
subitems.   There  is a string gadget labeled FUNCTION found on the editing
requesters for each of these objects which you must fill in with the proper
text  for  your  target  language.   PowerWindows  will  generate  a single
event-handler  for all of these structures.  You process your IntuiMessages
in the following ways:

     Gadgets:
          wait for an IntuiMessage of GADGETUP or GADGETDOWN
          get the object address from the IntuiMessage (this is
                    the gadget_address)
          Reply the message to free Intuition for other tasks
          invoke the event-handler with
                    HandleEvent(gadget_address)
     MenuItems and Subitems:
          wait for an IntuiMessage of MENUPICK
          get the code field from the IntuiMessage (this is the
                    MENUNUM)
          Reply the message to free Intuition for other tasks
          get the item_address from Intuition with
                    itemAddress(MENUNUM);
          invoke the event-handler with
                    HandleEvent(item_address);

The  event-handler  will, if the gadget or menuitem is matched, execute the
indicated function, passing the same object address through to the function
as  a  parameter.   Please  see  the example file for the language your are
working in for specific details.

Troubleshooting:

"I  can't  get  PW to show its menu!":  Try clicking in one of your windows
and pressing F1.  This will bring PW to the front and activate its window.

"I  can't  get my custom menu to display!":  Turn Auto Select off and click
in your window.  Press F1 when finished to return to the PW main menu.  Or,
select  the drag bar, foreground or close gadget of the window and then you
can  look at your menu.  Click inside it again to go back to the PW command
menu or press F1.

"How  do  I  make a custom knob for a PROPGADGET?":  Declare a proportional
gadget  and  load  in the IFF brush for the knob.  You can load brushes for
both the unselected and selected knob render.  Ta-da!

"When  I  load  in  an  image,  PowerWindows  seems  to HANG!":  PW is just
remapping  the  image.   Sometimes,  it  can  take  a  while.  A 320 x 200,
5-bitplane  image  can  take  up to 16 seconds to remap.  Don't panic, just
wait.   Or,  if  you  don't  need color remapping, turn off the Image color
remapping flag under the Preferences menu.

"I'm lost and I don't know what to do!":  You are probably in the middle of
a gadget command.  Press HELP.  It will tell you what you are doing and let
you cancel or continue doing it.  If that doesn't work, click inside one of
your  edit  windows  or  the  PW  command window and press F1.  This should
return you to the PW command level.

End.